home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / forth / docs / txtforth < prev   
Text File  |  1992-02-06  |  39KB  |  1,307 lines
  1.  
  2.  
  3. ARMFORTH 
  4.  
  5. (c) Davidsoft 1991
  6.  
  7.  
  8.  
  9. Based upon the language FORTH
  10.  
  11. Version 1.10
  12.  
  13. David Redman
  14. 33 Manor Road,
  15. Potters Bar,
  16. Herts.
  17. EN6 1DQ
  18.  
  19. Introduction
  20.  
  21.         ARMFORTH is a FORTH like language, making extensive use of RPN notation and stacks. many of the commands contained in the language are identical to their FORTH counterparts. However there are some differences. 
  22.  
  23. What ARMFORTH offers :
  24.         •       Multitasking :  - 8 separate processes.
  25.                 Each task has its own data, and return stacks.
  26.         •       Dynamic memory allocation words.
  27.                 ( malloc and free ).
  28.         •       File handling
  29.         •       An inbuilt editor written in ARMFORTH.
  30.         •       A WIMP version ( not internally multitasking)
  31.                 for rapid program development and testing in
  32.                 the DESKTOP environment.
  33.         •       32 bit stack and data manipulation
  34.         •       An assembler ( SOON )
  35.  
  36.         ARMFORTH is small, only 10K ( unsqueezed ) for the NON WIMP version and 11K for the WIMP. It is also faster than BASIC, as an example:
  37.  
  38.         Language                        empty loop to 1 million
  39.         ARMFORTH:               6 
  40.         BASIC:                  14 ( integer X%)
  41.                                         38 ( using x )
  42.         'C'                             2 (using integer)
  43.         
  44.         However the size of the code is also important, for the 'C' a mere 48K, for BASIC about 40bytes ( 40K counting ROM ) for ARMFORTH, 24 bytes ( 10K including KERNEL ).
  45. Data Types
  46.  
  47.         ARMFORTH has only has two real data types, bytes and words, any others are created as they are needed and may be accessed by combining the two supported types.
  48.         All stack entries are 32 bits wide and may be used in any fashion the user requires, the only condition is that EVERY stack entry be WORD aligned after any created structure has been pushed onto it.
  49.         There are built in string printing support and compile commands but string manipulation routines such as strcpy are not, they are provided in the stringlib file though, and any additional special structure handling routines would have to be written.
  50.         The format of an ARMFORTH string is a length as the top stack entry with the string contained on the stack in 4 byte chunks starting with the first letter.
  51.  
  52. File Handling
  53.  
  54.         ARMFORTH has RISCOS file handling and uses commands that are very similar to BASIC. These are LOAD, OPEN, CLOSE, PTR, EXT, EXT#, EOF and CLOSE ( These commands are covered in more detail later on in this manual ).
  55.         ARMFORTH filing commands ( open and load ) expect a string on the stack when they execute, the remainder expect a file handle. 
  56.         ARMFORTH has a file stack that may be nested 7 deep, this means that when loading a file it could be split into functional libraries ( like the editor with stringlib ). If more than 7 files are opened at one time ARMFORTH will abort and it is a good idea to restart and reduce the file depth.
  57. Multitasking
  58.  
  59.         It is import to appreciate that when multitasking the tasks have separate data and stack spaces they share the same dictionary space. This means that any task which modified the dictionary could crash the other tasks.
  60.         This is not an unacceptable risk because the advantages far surpass this problem, for example multiple copies of the same code could be running, with different data. Processes may communicate with each other via common data in the dictionary ( semiphores may be implemented ), obviously the system could be abused by forking a process that would compile a file into the background with disastrous results.
  61.         Finally all tasks have equal priority and are run in a round robin type task queue and are swapped every 10ms ( or as close to that interval as possible ) - It should be noted that assember code will NOT multitask in forth until it exits back into the ARMFORTH kernel ( this is how semaphores may be implemented ).
  62. Flow Control
  63.  
  64.         This section will detail all the flow control commands used in ARMFORTH. In the examples a brief description of what the example will do will be given and then the actual code. Type exactly what you see written, a <RETURN> means press the RETURN key, everything after the <RETURN> up to the OK shows what ARMFORTH will produce, unless surrounded by [[ ]] which means type the contents.
  65.  
  66. BEGIN..END
  67.         This is the fastest and most primitive of ARMFORTH loop constructs. The code between the BEGIN and the END will be executed if the top stack entry is zero when the END is reached, at which point program execution will continue with the code following the END.
  68. Example: wait for the user to press space then print DONE.
  69.                 :wait begin get aspace = end [ DONE ] ;
  70.                 wait <RETURN> [[A B C <SPACE> ]] OK
  71.  
  72. DO ... LOOP
  73.         The most basic of ARMFORTH loop commands. It takes 2 stack entries and starting at the top stack entry count up to the second stack entry. The loop will always execute at least once.  The is no real loop variable but a loop variable may be accessed by the index i,j or k depending upon the depth of nesting ( i is first ). The addition is made BEFORE comparison of the terminating condition.
  74. Example:  to count from 0 to 9 displaying each number
  75.                 : test cr 10 0 do i . loop ;
  76.                 test <RETURN>
  77.                 0 1 2 3 4 5 6 7 8 9 OK
  78.  
  79.  
  80. DO ... +LOOP
  81.         similar to DO..LOOP but the stack entry before the execution of +LOOP is the increment.
  82. Example: to count from 0 to 8 in 2's
  83.                 : test cr 10 0 do i . 2 +loop ;
  84.                 test <RETURN>
  85.                 0  2  4  6  8  OK
  86.  
  87. LEAVE
  88.         This command will cause the currently executing do..loop or do..+loop to terminate ( it set the current count to be the finishing value ). It will not prevent a loop from executing less than once.
  89.  
  90. IF..THEN
  91.         Provides a simple way to conditionally execute code, if the top stack entry is NON zero when the if evaluates then the code between the IF and THEN is executed, if the stack entry was zero then execution skips to the code following the then.
  92. Example: print BEEP if a 1 is the top stack entry.
  93.                 : bleep if [ BEEP ] then ;
  94.                 0 bleep <RETURN> OK
  95.                 1 bleep <RETURN> BEEP OK
  96.  
  97. IF..ELSE..THEN
  98.         Provides facilities for executing one section of code OR another. If the top stack entry is true the code between the IF and ELSE is executed otherwise the code between the ELSE and the THEN will be executed. Program execution will continue with the code following the THEN in both cases.
  99. Example: if top stack entry is 1 print TRUE else print FALSE.
  100.                 : test if [ TRUE ] else [ FALSE ] then ;
  101.                 1 test <RETURN> TRUE OK
  102.                 0 test <RETURN> FALSE OK
  103. BEGIN..IF..WHILE
  104.         Provides a form of WHILE loop in ARMFORTH, the code between BEGIN and IF will be repeated while the top stack entry upon execution of the IF is NON zero, if it is true then the code between the IF and WHILE will be executed and a branch made back to the code following BEGIN. If the stack contained a zero when the IF evaluated the code following the WHILE while be executed.
  105. Example: print keys while <space> is not pressed.
  106.                 : test begin get dup 32 <> if vdu while [ DONE ] ;
  107.                 test [[a]]a[[b]]b[[<SPACE>]] DONE OK
  108.  
  109. BEGIN..IF..ELSE..WHILE
  110.         This loop construct is essentially the opposite of the loop above. It executes the code between the BEGIN and THE IF while the top stack entry is false and terminates when it is true.
  111. Example: 
  112.                 : test begin get dup 32 = if [ Done ] else vdu while ;
  113.                 test [[a]]a[[b]]b[[<SPACE>]] DONE OK
  114.  
  115. FORTH command list 
  116.  
  117. Some Syntax: 
  118.  
  119. <...> means item must be present / or will be created
  120. [   ] means optionally created. 
  121.  
  122. About this list: 
  123.  
  124. Command : name of command
  125. Type    : variable / command / compiling command
  126. Arguments       : <entry1> <entry2> <entry3> .. <nth entry>
  127. Returns : <entry1> <entry2> <entry3> .. <nth entry> 
  128.  
  129. Command : editv
  130. Type    : system variable 
  131. Arguments       :  
  132. Returns : address of edit vector 
  133. Description
  134. used if a replacement 'inline' input routine is written.
  135.  
  136. Command : base
  137. Type    : system variable 
  138. Arguments       : 
  139. Returns : address of system base 
  140. Description
  141. used to change the current number entry mode base
  142. Example: 16 mode ! - sets hex numeric entry
  143.  
  144. Command : compiler
  145. Type    : system variable 
  146. Arguments       :  
  147. Returns :  <entry>
  148. Description
  149. Pushes the address of the compiler variable which points to the last entry in the COMPILER vocabulary
  150.  
  151. Command : context
  152. Type    : system variable 
  153. Arguments       :  
  154. Returns :  <entry>
  155. Description
  156. Pushes the address of the system CONTEXT variable to the stack.
  157.  
  158. Command : current
  159. Type    : system variable 
  160. Arguments       :  
  161. Returns :  <entry>
  162. Description
  163. Pushes the address of the current vocabulary variable.
  164.  
  165. Command : dp
  166. Type    : system variable 
  167. Arguments       :  
  168. Returns : address of dictionary pointer variable 
  169. Description
  170. used to locate the current dp value
  171.  
  172.  
  173. Command: himem
  174. Type    : system variable 
  175. Arguments       :  
  176. Returns :  address of himem variable
  177. Description
  178. the word at this address is the value of the highest address that the dictionary pointer could increase towards before corrupting the stack space.
  179.  
  180. Command : lbp
  181. Type    : system variable 
  182. Arguments       :  
  183. Returns : address of line buffer pointer 
  184. Description
  185. used by inline and token for character entry and tokenisation
  186.  
  187. Command : mode
  188. Type    : system variable 
  189. Arguments       :  
  190. Returns : address of mode variable 
  191. Description
  192. indicates if system is in compile ( 1 ) or execute mode ( 0 )
  193.  
  194. Command : state
  195. Type    : system variable 
  196. Arguments       :  
  197. Returns : address of state variable 
  198. Description
  199. used with mode to decide if a word is compiled or executed
  200.  
  201.  
  202. Command : core
  203. Type    : system variable 
  204. Arguments       :  
  205. Returns :  
  206. Description
  207. Invokes the CORE vocabulary.
  208.  
  209. Command : quit
  210. Type    : command 
  211. Arguments       :  
  212. Returns :  
  213. Description
  214. exits from the forth environment.
  215.  
  216. Command : singletask
  217. Type    : command 
  218. Arguments       :  
  219. Returns :  
  220. Description
  221. stop multitasking
  222.  
  223. Command : multitask
  224. Type    : command 
  225. Arguments       :  
  226. Returns :  
  227. Description
  228. start multitasking
  229.  
  230.  
  231. Command : fork
  232. Type    : command 
  233. Arguments       : address of routine to fork 
  234. Returns : 
  235. Description
  236. takes address of routine from stack and starts the task when the next quantam elapses.
  237. Example: ' test fork - will run test as a background task
  238.  
  239. Command : taskblock
  240. Type    : command 
  241. Arguments       :  
  242. Returns :  
  243. Description
  244.  
  245. Command : quantam
  246. Type    : system variable 
  247. Arguments       :  
  248. Returns : address of multitask data block 
  249. Description
  250. used by multitasking code to get access to task queues and status. enables utilities to be written to examine task status etc. DO NOT MODIFY THE DATA BLOCK THIS POINTS TO.
  251.  
  252. Command : token
  253. Type    : command 
  254. Arguments       : <separator> 
  255. Returns :  
  256. Description
  257. tokenises the next 'word' separated by <separator> into the dictionary space
  258. Example : aspace token - tokenises next word in input buffer
  259.  
  260. Command : search
  261. Type    : command 
  262. Arguments       : <address> 
  263. Returns : <status> [<address>] 
  264. Description
  265. used to locate a key word code address. The dictionary pointed to be <address> will be searched. if the token is found then status will be 0 and the address of the routine will be pushed to the stack, otherwise a 1 will be pushed.
  266.  
  267. Command : 0
  268. Type    : command / arithmetic
  269. Arguments       :  
  270. Returns : 0 
  271. Description
  272. pushes a zero onto the data stack
  273.  
  274. Command : 1
  275. Type    : command / arithmetic
  276. Arguments       :  
  277. Returns : 1 
  278. Description
  279. pushes a 1 onto data stack
  280.  
  281. Command : -1 
  282. Type    : command / arithmetic
  283. Arguments       :  
  284. Returns : -1 
  285. Description
  286. pushes -1 onto the data stack
  287.  
  288.  
  289. Command : 1+ 
  290. Type    : command / arithmetic
  291. Arguments       : <entry1> 
  292. Returns : <entry1>+1 
  293. Description
  294. adds 1 to top stack entry
  295.  
  296. Command : 1- 
  297. Type    : command / arithmetic
  298. Arguments       : <entry1> 
  299. Returns : <entry1>-1 
  300. Description
  301. subtracts 1 from the top stack entry
  302.  
  303. Command : 2+ 
  304. Type    : command / arithmetic
  305. Arguments       : <entry1> 
  306. Returns : <entry1>+2 
  307. Description
  308. adds 2 to top stack entry
  309.  
  310. Command : 2- 
  311. Type    : command / arithmetic
  312. Arguments       : <entry1> 
  313. Returns : <entry1>-2 
  314. Description
  315. subtracts 2 from the top stack entry
  316.  
  317. Command : 2* 
  318. Type    : command / arithmetic
  319. Arguments       : <entry1> 
  320. Returns : <entry1>*2 
  321. Description
  322. multiplies top stack entry by 2
  323. Command : 2/ 
  324. Type    : command / arithmetic
  325. Arguments       : <entry1> 
  326. Returns : <entry1> DIV 2 
  327. Description
  328. divides to stack entry by 2
  329.  
  330. Command : 4+ 
  331. Type    : command / arithmetic
  332. Arguments       : <entry1> 
  333. Returns:         <entry1>+4 
  334. Description
  335. adds 4 to top stack entry
  336.  
  337. Command : 4- 
  338. Type    : command / arithmetic
  339. Arguments       : <entry1> 
  340. Returns : <entry1>-4 
  341. Description
  342. subtracts 4 from the top stack entry
  343.  
  344. Command : 4* 
  345. Type    : command / arithmetic
  346. Arguments       : <entry1> 
  347. Returns : <entry1>*4 
  348. Description
  349. multiplies to stack entry by 4
  350.  
  351. Command : 4/ 
  352. Type    : command / arithmetic
  353. Arguments       : <entry1> 
  354. Returns : <entry1> DIV 4 
  355. Description
  356. divides top stack entry by 4
  357. Command : +
  358. Type    : command / arithmetic
  359. Arguments       : <entry1> <entry2> 
  360. Returns : <entry1>+<entry2> 
  361. Description
  362. adds top 2 stack entries and pushes the result
  363.  
  364. Command : -
  365. Type    : command / arithmetic
  366. Arguments       : <entry1> <entry2> 
  367. Returns : <entry2>-<entry1>  
  368. Description
  369. subtracts top 2 stack entries and pushes result
  370.  
  371. Command : *
  372. Type    : command / arithmetic
  373. Arguments       : <entry1> <entry2> 
  374. Returns : <entry2>*<entry1>  
  375. Description
  376. multiply produces a 32 bit result
  377.  
  378. Command : /
  379. Type    : command / arithmetic
  380. Arguments       : <entry1> <entry2> 
  381. Returns : <entry2>DIV<entry1> <entry2>MOD<entry1>  
  382. Description
  383. divides 2nd entry by first and leaves DIV and MOD on stack
  384.  
  385. Command : abs
  386. Type    : command / arithmetic
  387. Arguments       : <entry1> 
  388. Returns : <entry1> 
  389. Description
  390. if negative makes entry positive
  391. Command : minus
  392. Type    : command / arithmetic
  393. Arguments       : <entry1> 
  394. Returns : -<entry1> 
  395. Description
  396. changes sign of top stack entry
  397.  
  398. Command : min
  399. Type    : command / arithmetic
  400. Arguments       : <entry1> <entry2> 
  401. Returns : <entry> 
  402. Description
  403. leaves the smaller of the 2 top entries on the stack
  404.  
  405. Command : max
  406. Type    : command / arithmetic
  407. Arguments       : <entry1> <entry2> 
  408. Returns : <entry> 
  409. Description
  410. leaves the larger of the 2 top entries on the stack
  411.  
  412. Command : <<
  413. Type    : command / arithmetic
  414. Arguments       : <entry1> <entry2> 
  415. Returns : <entry> 
  416. Description
  417. leaves <entry2> left shifted by <entry1> bits on the stack
  418.  
  419. Command : >>
  420. Type    : command / arithmetic
  421. Arguments       : <entry1> <entry2> 
  422. Returns : <entry> 
  423. Description
  424. leaves <entry2> right shifted by <entry1> bits on the stack 
  425. Command : not
  426. Type    : command / logic
  427. Arguments       : <entry> 
  428. Returns : <entry> 
  429. Description
  430. if top stack entry is not zero then push 1 else push 0
  431.  
  432. Command : and
  433. Type    : command / logic
  434. Arguments       : <entry1> <entry2> 
  435. Returns : <entry> 
  436. Description
  437. replaces the top 2 stack entries by the bitwise AND of them.
  438.  
  439. Command : eor
  440. Type    : command / logic
  441. Arguments       : <entry1> <entry2> 
  442. Returns : <entry> 
  443. Description
  444. replaces the top 2 stack entries by the bitwise EOR of them
  445.  
  446. Command : or
  447. Type    : command / logic
  448. Arguments       : <entry1> <entry2> 
  449. Returns : <entry> 
  450. Description
  451. replaces the top 2 stack entries by the bitwise OR of them
  452.  
  453. Command : bic
  454. Type    : command / logic
  455. Arguments       : <entry1> <entry2> 
  456. Returns : <entry> 
  457. Description
  458. clears bits in entry2 that are set in entry 1
  459. Command : tst
  460. Type    : command / logic
  461. Arguments       : <entry1> <entry2> 
  462. Returns : <entry> 
  463. Description
  464. if bit number <entry1> in entry2 is set then push 1 else push 0
  465.  
  466. Command : ror
  467. Type    : command / logic
  468. Arguments       :  <entry1> <entry2>
  469. Returns :  <entry>
  470. Description
  471. rotate <entry2> by <entry1> bits right and push result onto stack.
  472.  
  473. Command : >
  474. Type    : command / control
  475. Arguments       : <entry1> <entry2> 
  476. Returns : <entry> 
  477. Description
  478. if entry2 > entry1 then push 1 else push 0
  479.  
  480. Command: >=
  481. Type    : command / control
  482. Arguments       : <entry1> <entry2> 
  483. Returns : <entry> 
  484. Description
  485. if entry2 >= entry1 then push 1 else push 0
  486.  
  487. Command : <
  488. Type    : command / control
  489. Arguments       : <entry1> <entry2> 
  490. Returns : <entry> 
  491. Description
  492. if entry2 < entry1 then push 1 else push 0
  493.  
  494. Command : <=
  495. Type    : command / control 
  496. Arguments       : <entry1> <entry2> 
  497. Returns : <entry> 
  498. Description
  499. if entry2 <= entry1 then push 1 else push 0
  500.  
  501. Command : =
  502. Type    : command / control
  503. Arguments       : <entry1> <entry2> 
  504. Returns : <entry> 
  505. Description
  506. if entry2 = entry1 then push 1 else push 0
  507.  
  508. Command : <>
  509. Type    : command / control
  510. Arguments       : <entry1> <entry2> 
  511. Returns : <entry> 
  512. Description
  513. if entry2 <> entry1 then push 1 else push 0
  514.  
  515. Command : 0=
  516. Type    : command / control
  517. Arguments       : <entry1> 
  518. Returns : <entry> 
  519. Description
  520. if entry1 = 0 then push 1 else push 0
  521. Command : 0<
  522. Type    : command / control
  523. Arguments       : <entry1> 
  524. Returns : <entry> 
  525. Description
  526. if entry1 < 0 then push 1 else push 0
  527.  
  528. Command : 0>
  529. Type    : command / control
  530. Arguments       : <entry1> 
  531. Returns : <entry> 
  532. Description
  533. if entry1 > 0 then push 1 else push 0
  534.  
  535. Command : execute
  536. Type    : command
  537. Arguments       :  <entry>
  538. Returns :  
  539. Description
  540. pops the top stack entry and will execute the ARMFORTH code at that address.
  541.  
  542. Command : abort 
  543. Type    : system control
  544. Arguments       :  
  545. Returns :  
  546. Description
  547. restarts the interpreter after a fault
  548.  
  549.  
  550. Command : bin
  551. Type    : command
  552. Arguments       :  
  553. Returns :  
  554. Description
  555. selects binary display mode
  556.  
  557. Command : oct
  558. Type    : command 
  559. Arguments       : 
  560. Returns :  
  561. Description
  562. selects octal display mode
  563.  
  564. Command : dec
  565. Type    : command 
  566. Arguments       :  
  567. Returns :  
  568. Description
  569. selects decimal display mode
  570.  
  571. Command : hex
  572. Type    : command 
  573. Arguments       :  
  574. Returns :  
  575. Description
  576. selects hex display mode
  577.  
  578.  
  579. Command : entry
  580. Type    : command 
  581. Arguments       :  
  582. Returns : <entry>
  583. Description
  584. pushes the address of the first header word in the latest entry in the CURRENT vocabulary.
  585.  
  586. Command : here 
  587. Type    : command
  588. Arguments       : 
  589. Returns :  <entry>
  590. Description
  591. pushes the address of the next free dictionary location onto the data stack.
  592.  
  593. Command : ca! 
  594. Type    : command
  595. Arguments       :  <entry>
  596. Returns :  
  597. Description
  598. Stores the top stack entry in the word address location of the latest entry in the CURRENT vocabulary.
  599.  
  600. Command : aspace
  601. Type    : command 
  602. Arguments       :  
  603. Returns : 32 
  604. Description
  605. pushes the ascii value of a space ( 32 ) onto the data stack.
  606.  
  607.  
  608. Command : ,
  609. Type    : command 
  610. Arguments       : <entry> 
  611. Returns :  
  612. Description
  613. encloses the top data stack entry in the dictionary and advances the dictionary pointer by 1 word.
  614.  
  615. Command : c,
  616. Type    : command 
  617. Arguments       : <entry> 
  618. Returns :  
  619. Description
  620. encloses the lowest byte of the top data stack entry in the dictionary and moves the dictionary pointer forward by 1. CARE IS RECOMMENDED !!!
  621.  
  622. Command : buffer
  623. Type    : system variable 
  624. Arguments       :  
  625. Returns : <address of the input buffer> 
  626. Description
  627. used to get characters from the input buffer
  628.  
  629. Command : !
  630. Type    : command / memory 
  631. Arguments       : <entry1> <entry2> 
  632. Returns :  
  633. Description
  634. puts the word entry2 in the address entry1
  635.  
  636.  
  637. Command : c!
  638. Type    : command / memory 
  639. Arguments       : <entry1> <entry2> 
  640. Returns :  
  641. Description
  642. puts the lsb of the word entry2 into the address entry1
  643.  
  644. Command : +!
  645. Type    : command / memory 
  646. Arguments       : <entry1> <entry2> 
  647. Returns :  
  648. Description
  649. adds entry2 to the value at address entry1
  650.  
  651. Command : c+!
  652. Type    : command / memory 
  653. Arguments       : <entry1> <entry2> 
  654. Returns :  
  655. Description
  656. adds the lsb of entry2 to the byte at address entry1
  657.  
  658. Command : 0set
  659. Type    : command / memory 
  660. Arguments       : <entry1> 
  661. Returns :  
  662. Description
  663. zeros the word at address entry1
  664.  
  665. Command : 1set
  666. Type    : command / memory 
  667. Arguments       : <entry1> 
  668. Returns :  
  669. Description
  670. sets the word at address entry1 to 1
  671. Command : c0set
  672. Type    : command / memory 
  673. Arguments       : <entry1> 
  674. Returns :  
  675. Description
  676. sets the byte at address entry1 to zero
  677.  
  678. Command : c1set
  679. Type    : command / memory 
  680. Arguments       : <entry1> 
  681. Returns :  
  682. Description
  683. sets the byte at address entry1 to 1
  684.  
  685. Command : @
  686. Type    : command / memory 
  687. Arguments       : <entry1> 
  688. Returns : <entry> 
  689. Description
  690. pushes the word at address entry1 onto the data stack
  691.  
  692. Command : c@
  693. Type    : command / memory 
  694. Arguments       : <entry1> 
  695. Returns : <entry> 
  696. Description
  697. pushes the byte ( expanded to 32 bits ) at address entry1 onto the data stack
  698.  
  699.  
  700. Command : align
  701. Type    : command / memory 
  702. Arguments       : <entry1> 
  703. Returns : <entry> 
  704. Description
  705. replaces entry1 with the nearest value rounded up to a word boundary
  706. Example : dec 5 align . - would display 8
  707.  
  708. Command : over
  709. Type    : command / stack 
  710. Arguments       : <entry1> <entry2> 
  711. Returns : <entry2> <entry1> <entry2> 
  712. Description
  713. over pushes the second stack entry onto the data stack
  714.  
  715. Command : 2over
  716. Type    : command / stack 
  717. Arguments       : <entry1> <entry2> <entry3> 
  718. Returns : <entry3> <entry1> <entry2> <entry3> 
  719. Description
  720. 2over pushes the third stack entry onto the data stack.
  721.  
  722. Command : swap
  723. Type    : command / stack 
  724. Arguments       : <entry1> <entry2> 
  725. Returns : <entry2> <entry1> 
  726. Description
  727. swaps the top 2 stack entries
  728.  
  729.  
  730. Command : 2swap
  731. Type    : command / stack 
  732. Arguments       : <entry1> <entry2> <entry3> 
  733. Returns : <entry3> <entry2> <entry1> 
  734. Description
  735. swaps the first and third stack entries.
  736.  
  737. Command : dup
  738. Type    : command / stack 
  739. Arguments       :
  740. Returns : <entry1> <entry1> 
  741. Description
  742. pushes the top stack entry onto the stack.
  743.  
  744. Command : drop
  745. Type    : command / stack 
  746. Arguments               : <entry1> <entry2> 
  747. Returns : <entry2> 
  748. Description
  749. pops the top stack entry.
  750.  
  751. Command:         2dup
  752. Type    : command / stack 
  753. Arguments       : <entry1> 
  754. Returns : <entry1> <entry1> <entry1> 
  755. Description
  756. duplicates the top stack entry twice.
  757.  
  758. Command : ?rs 
  759. Type    : command / stack
  760. Arguments       :  
  761. Returns :  <entry>
  762. Description
  763. pushes the value of the current return stack pointer,
  764. Command : ?sp
  765. Type    : command / stack
  766. Arguments       :  
  767. Returns :  <entry>
  768. Description
  769. pushes the value of the data stack pointer prior to the push onto that data stack.
  770.  
  771. Command : i 
  772. Type    : compile / loop index
  773. Arguments       :  
  774. Returns :  <entry>
  775. Description
  776. pushes the value of the inner most loop index onto the data stack.
  777.  
  778. Command : j 
  779. Type    : compile / loop index
  780. Arguments       :  
  781. Returns :  <entry>
  782. Description
  783. pushes the value of the 2nd inner most loop index onto the data stack.
  784.  
  785. Command : k 
  786. Type    : compile / loop
  787. Arguments       :  
  788. Returns :  <entry>
  789. Description
  790. pushes the value of the 3rd inner most loop index onto the data stack.
  791.  
  792.  
  793. Command : -sp
  794. Type    : command / stack 
  795. Arguments       : <     entry1> 
  796. Returns :  
  797. Description
  798. this command will reduce the depth of the stack by <entry1> bytes. CARE is recommended.... always leave SP on a word boundary. YOU HAVE BEEN WARNED
  799.  
  800. Command : +sp
  801. Type    : command / stack 
  802. Arguments       : <entry1> 
  803. Returns :  
  804. Description
  805. this command will effectively push <entry1> bytes onto the stack although no actual valid data will be present. Used mainly for reserving stack space. CARE: always ensure that the stack remains on a word boundary when you have finished. YOU HAVE BEEN WARNED.
  806.  
  807. Command : rrot 
  808. Type    : command / stack
  809. Arguments       :  <entry1> <entry2> <entry3>
  810. Returns :  <entry2> <entry3> <entry1>
  811. Description
  812. rotates the top three stack entries once to the right.
  813. Example : 1 2 3 rrot . . . gives 2 1 3
  814.  
  815.  
  816. Command : lrot 
  817. Type    : command / stack
  818. Arguments       :  <entry1> <entry2> <entry3>
  819. Returns :  <entry3> <entry1> <entry2>
  820. Description
  821. rotates the top 3 stack entries to the left by one slot.
  822. Example :  1 2 3 lrot . . . gives 1 3  2
  823.  
  824. Command : rs>ds
  825. Type    : command / inter-stack 
  826. Arguments       :  
  827. Returns : <top entry from return stack> 
  828. Description
  829. pops the top entry from the return stack and pushes it onto the data stack. CARE is recommended as popping a return address without careful consideration will result in the forth interpreter crashing. YOU HAVE BEEN WARNED
  830.  
  831. Command : ds>rs
  832. Type    : command / inter-stack 
  833. Arguments: <entry> 
  834. Returns :  
  835. Description
  836. pops <entry> from the data stack and pushes it onto the return stack. CARE is recommended here as a ds>rs without an rs>ds will destroy the return stack and could kill forth. YOU HAVE BEEN WARNED
  837.  
  838. Command : .
  839. Type    : command / IO 
  840. Arguments       : <entry1> 
  841. Returns :  
  842. Description
  843. displays the top stack entry in the currently selected base.
  844. Command : .r
  845. Type    : command / IO 
  846. Arguments        <entry1> <entry2> 
  847. Returns :  
  848. Description
  849. displays the <entry2> in a field width of <entry1>
  850.  
  851. Command : cr
  852. Type    : command / IO 
  853. Arguments       :  
  854. Returns :  
  855. Description
  856. echoes a CR/LF to the screen.
  857.  
  858. Command : inkey
  859. Type    : command / IO 
  860. Arguments       :  
  861. Returns : <status> [<key number>] 
  862. Description
  863. inkey waits .01 of a second for a key to be pressed, if no key is pressed it pushes a 0 otherwise it pushes the key and 1.
  864.  
  865. Command : get
  866. Type    : command / IO 
  867. Arguments       :  
  868. Returns : <char> 
  869. Description
  870. get waits indefinitely until a key is pressed and then it pushes the ascii value of the key onto the stack.
  871.  
  872.  
  873. Command : space
  874. Type    : command / IO 
  875. Arguments       :  
  876. Returns :  
  877. Description
  878. prints a space to the screen.
  879.  
  880. Command : echo
  881. Type    : command / IO 
  882. Arguments       : <ascii code> 
  883. Returns :  
  884. Description
  885. pops the stack and echoes the lsb of the word to the display.
  886.  
  887. Command : cls
  888. Type    : command / IO 
  889. Arguments       :  
  890. Returns :  
  891. Description
  892. clears the screen. It is a more efficient version of 12 echo.
  893.  
  894. Command : pos
  895. Type    : command / IO 
  896. Arguments       :  
  897. Returns : <ypos> <xpos> 
  898. Description
  899. pushes the current position (x,y) of the text cursor onto the stack.
  900.  
  901.  
  902. Command : tab
  903. Type    : command / IO 
  904. Arguments       : <ypos> <xpos> 
  905. Returns :  
  906. Description
  907. moves the text cursor to position (xpos,ypos) on the screen.
  908.  
  909. Command : malloc
  910. Type    : command / memory 
  911. Arguments       : <size> 
  912. Returns : <status> [ <address> ] 
  913. Description
  914. malloc will try to allocate a space of <size> bytes, if unsuccessful <status> will be 0 else <status> will be 1 and <address> will be the address of the allocated block.
  915.  
  916. Command : free
  917. Type    : command / memory 
  918. Arguments       : <address> 
  919. Returns :  
  920. Description
  921. free will deallocate the block pointed to be <address>. No error will be reported if it is unsuccessful.
  922.  
  923. Command : ?
  924. Type    : command / IO 
  925. Arguments       : <entry> 
  926. Returns :  
  927. Description
  928. this command will display the word at the address pointed to by <entry> in the current number base on the display.
  929.  
  930.  
  931. Command : c?
  932. Type    : command / IO 
  933. Arguments       : 
  934. Returns :  
  935. Description
  936. this command will display the byte at the address pointed to by <entry> in the current number base on the display.
  937.  
  938. Command : forget 
  939. Type    : dictionary management
  940. Arguments       :  
  941. Returns :  
  942. Description
  943. Searches the current vocabulary for the keyword following the forget and will remove all keyword from that point forwards. It is to forget priority to completely erase the ARMFORTH dictionary.
  944.  
  945. Command : ' 
  946. Type    : command / vocabulary
  947. Arguments       :  
  948. Returns :  [<entry>] 
  949. Description
  950. scans the token following the tick in the input buffer and searches the CURRENT and CONTEXT vocabularies. If the word is found its execution address is pushed to the stack otherwise the keyword followed by a question mark will be displayed.
  951.  
  952.  
  953. Command : definitions 
  954. Type    : command / vocabulary
  955. Arguments       :  
  956. Returns :  
  957. Description
  958. sets the system variable CURRENT to the value in CONTEXT.
  959.  
  960. Command : create 
  961. Type    : defining word
  962. Arguments       :  
  963. Returns :  
  964. Description
  965. creates a dictionary header for the primitive keyword whose name follows create and links it to the vocabulary.
  966.  
  967. Command : : 
  968. Type    : compiling word
  969. Arguments       :  
  970. Returns :  
  971. Description
  972. creates a token for the keyword following the : in the buffer, links it to the current vocabulary and sets the system in compile mode.
  973.  
  974. Command : next
  975. Type    : compiling word
  976. Arguments       :  
  977. Returns :  
  978. Description
  979. encloses a jump to the inner interpreter NEXT routine in the dictionary.
  980.  
  981.  
  982. Command : constant
  983. Type    : defining word
  984. Arguments       :  <entry>
  985. Returns :  
  986. Description
  987. creates a word length constant dictionary entry whose value is the top stack entry and whose name follows the constant keyword. When the keyword name is executed the value of the constant will be pushed to the data stack.
  988.  
  989. Command : variable 
  990. Arguments       :  <entry>
  991. Returns :  
  992. Description
  993. creates a word length variable entry whose value is the top stack entry and whose name follows the constant keyword. When the keyword name is executed the address of the keyword is pushed to the stack.
  994.  
  995. Command : immediate 
  996. Type    : vocabulary management
  997. Arguments       :  
  998. Returns :  
  999. Description
  1000. delinks the last keyword from the CURRENT vocabulary and links it to the COMPILER vocabulary. Adds keywords to the compiler vocabulary.
  1001.  
  1002.  
  1003. Command : <builds 
  1004. Type    : defining word
  1005. Arguments       :  
  1006. Returns :  
  1007. Description
  1008. creates a CONSTANT keyword definition with an initial value of 0. The name is the token following <builds in the input buffer. MUST be terminated by a DOES> keyword.
  1009.  
  1010. Command : does> 
  1011. Type    : program control
  1012. Arguments       :  <return stack entry1> <return stack entry2>
  1013. Returns :  
  1014. Description
  1015. replaces the first word in the code body of the latest entry in the vocabulary with the top return stack entry and replaces the code address with the second return stack entry.
  1016.  
  1017. Command : vocabulary 
  1018. Type    : defining word
  1019. Arguments       :  
  1020. Returns :  
  1021. Description
  1022. creates a keyword whose name follows it , with an initial link to the latest entry in the CURRENT vocabulary. When executed it sets CURRENT to the link address. Used for defining new vocabularies.
  1023.  
  1024.  
  1025. Command : (
  1026. Type    : command / string operator 
  1027. Arguments       :  
  1028. Returns : loads of stuff - see description
  1029. Description
  1030. This command will copy the string that is enclosed by the brackets () to the data stack. it will then push the length of the string onto the data stack. The string will be terminated by a 0 byte starting at the address after the length word has been popped.
  1031.  
  1032. Command :  type
  1033. Type    : command / string display 
  1034. Arguments       : <length> <loads of words marking string> 
  1035. Returns :  
  1036. Description
  1037. this command will print the next <length> bytes from the top of the data stack. after completion the stack has the string removed as is aligned to a word boundary.
  1038.  
  1039. Command : close
  1040. Type    : command / Filing 
  1041. Arguments       : <file handle> 
  1042. Returns :  
  1043. Description
  1044. this command will close the file that has a file handle <file handle>. a zero value for <file handle> will close ALL system files - this could be dangerous.
  1045.  
  1046.  
  1047. Command : load
  1048. Type    : command / filing 
  1049. Arguments       : <length> <string> 
  1050. Returns :  
  1051. Description
  1052. this command will load the forth file identified by the string that is on the top of the stack ( see the '(' entry earlier ).
  1053.  
  1054. Command : open
  1055. Type    : command / filing 
  1056. Arguments       : <string>
  1057. Returns : <status> [<handle>] 
  1058. Description
  1059. open takes a filename string ( in type format ) from the stack and tries to open the file with read/write or create access. This means if the file exists it may be modified, and if not it will be created. If an error occurs then a zero will be pushed to the stack otherwise a 1 and the handle are pushed to the stack.
  1060.  
  1061. Command : ptr#
  1062. Type    : command / filing
  1063. Arguments       : <offset> <handle>
  1064. Returns :
  1065. Description
  1066. ptr# will move the filepointer of the file <handle> up to position <offset> in the file, extending the file if need be. If 0 is used as the offset the file may be read from the start.
  1067.  
  1068.  
  1069. Command : #ptr
  1070. Type    : command / filing
  1071. Arguments       : <handle>
  1072. Returns : <offset>
  1073. Description
  1074. #ptr will return the current position of the file pointer within the file selected by <handle> and push it onto the data stack.
  1075.  
  1076. Command : putc 
  1077. Arguments       :  <data> <handle>
  1078. Returns :  
  1079. Description
  1080. putc will write a lsb of <data> into the file selected by <handle>. Care should be taken as all files are opened read/write and may be modified. 
  1081.  
  1082. Command : getc 
  1083. Type    : command / filing
  1084. Arguments       : <handle>
  1085. Returns :  <data>
  1086. Description
  1087. getc will read one byte from the selected file, expand it up to 32 bits and push it onto the stack.
  1088.  
  1089. Command : putw 
  1090. Type    : command / filing
  1091. Arguments       :  <data> <handle>
  1092. Returns :  
  1093. Description
  1094. putw will write <data> as a 32 bit word into the file selected by <handle>, it is written lsb first.
  1095.  
  1096.  
  1097. Command : getw 
  1098. Type    : command / filing
  1099. Arguments       :  <handle>
  1100. Returns :  <data>
  1101. Description
  1102. getw will read 4 bytes from the file selected by <handle> and push them onto the stack as a 32 bit word. The bytes are read lsb first.
  1103.  
  1104. Command : eof 
  1105. Arguments       : <handle>
  1106. Returns : <status>
  1107. Description
  1108. returns 1 if end of file <handle> has been reached, -1 if a read has occurred past the end of file and 0 otherwise.
  1109.  
  1110. Command : save
  1111. Type    : command / HOST image dump 
  1112. Arguments       :  
  1113. Returns :  
  1114. Description
  1115. This command creates a file called image in the current directory that is a mirror image of the state of the forth machine when the command was typed. This does not include stacks or multitasking status - just the dictionary.
  1116.  
  1117. Command : oscli
  1118. Type    : command / HOST 
  1119. Arguments       : <string> 
  1120. Returns :  
  1121. Description
  1122. <string> is in '(' format and is passed unmodified to the operating system.
  1123.  
  1124. Command : vdu
  1125. Type    : command / IO / graphics 
  1126. Arguments       : <code> 
  1127. Returns :  
  1128. Description
  1129. The <code> will be sent to the vdu drivers - this command is similar to echo.
  1130.  
  1131. Command : plot
  1132. Type    : command / IO / graphics 
  1133. Arguments       : <code> <x> <y> 
  1134. Returns :  
  1135. Description
  1136. This command will pass the stack entries to the vdu drivers, it assumes that the correct number of stack entries is present. If not then the stack will underflow and indeterminate data will be passed to the drivers.
  1137.  
  1138. Command : colour
  1139. Type    : command / IO / graphics 
  1140. Arguments       : <colour> 
  1141. Returns :  
  1142. Description
  1143. passes the following control codes to the vdu drivers. 17 <colour> to select the text colour. vdu could be used but is less efficient.
  1144.  
  1145. Command : gcol
  1146. Type    : command / IO / graphics 
  1147. Arguments       :  <effect> <colour>
  1148. Returns :  
  1149. Description
  1150. used to select the type of plotting performed by the graphics commands.
  1151. Command : ;
  1152. Type    :  compile mode terminator
  1153. Arguments       :  
  1154. Returns :  
  1155. Description
  1156. semi-colon is used to terminate the definition of a new word, it exits from compile mode and enters execution mode. It writes the address of the interpreter routine semi into the dictionary and advance the pointer by 4.
  1157.  
  1158. Command : ;code 
  1159. Type    : compile mode terminator
  1160. Arguments       :  
  1161. Returns :  
  1162. Description
  1163. semi-colon-code is used to terminate a forth word definition and encloses the address of the hidden routine scode in the dictionary. Machine code or assembler follows the statement and will be executed when the defined keyword is invoked.
  1164.  
  1165. Command : end 
  1166. Type    : compiler directive / flow control
  1167. Arguments       : <entry>
  1168. Returns :  
  1169. Description
  1170. End is used to terminate a begin end construct. The address on the stack was the value of the dictionary pointer when begin was executed.
  1171.  
  1172.  
  1173. Command : end, 
  1174. Type    : compiler / definitions
  1175. Arguments       :  <entry> <entry>
  1176. Returns :  
  1177. Description
  1178. encloses the address of the program control directive in the dictionary, computes the relative jump value and writes it in the dictionary. Used in defining new compiler keywords.
  1179.  
  1180. Command : else 
  1181. Type    : compiler / flow control
  1182. Arguments       :  <entry>
  1183. Returns :  <entry>
  1184. Description
  1185. else encloses the address of the control directive in the dictionary, calculates the value of the relative jump and saves the current value of the dictionary on the stack. Used as part of an if..else..then clause.
  1186.  
  1187. Command : then 
  1188. Arguments       :  <entry>
  1189. Returns :  
  1190. Description
  1191. pops the stack, computes the difference between the address and the current values of the dictionary pointer and store the value in the dictionary.
  1192.  
  1193. Command : do 
  1194. Arguments       :  <start> <end>
  1195. Returns :  
  1196. Description
  1197. encloses the address of the control direct in the dictionary and pops the top two entries from the data stack and pushes them onto the return stack. 
  1198. Command : do, 
  1199. Type    : compiler / flow control
  1200. Arguments       : <entry>
  1201. Returns :  <entry>
  1202. Description
  1203. stores the top stack entry in the dictionary and pushes the new value of the dictionary pointer to the stack.
  1204.  
  1205. Command : if 
  1206. Type    : compiler / flow control
  1207. Arguments       :  
  1208. Returns :  <entry>
  1209. Description
  1210. stores the address of the control directive in the dictionary, reserves the next word in the dictionary and pushes its address to the stack.
  1211.  
  1212. Command : while 
  1213. Type    : compiler / flow control
  1214. Arguments       :  <entry> <entry>
  1215. Returns :  
  1216. Description
  1217. encloses the address of the control directive in the dictionary, the difference between the second stack entry and the dictionary pointer is calculated and enclosed as the jump offset, it also writes this offset into the address pointed to by the top stack entry.
  1218.  
  1219.  
  1220. Command : loop 
  1221. Type    : compiler / flow control
  1222. Arguments       :  <entry>
  1223. Returns :  
  1224. Description
  1225. encloses the address of the control directive in the dictionary and calculates the difference between <entry> and the current dictionary pointer. It then encloses this offset in the dictionary as the jump offset.
  1226.  
  1227. Command : +loop 
  1228. Type    : compiler / flow control
  1229. Arguments       :  <entry>
  1230. Returns :  
  1231. Description
  1232. encloses the address of the +loop control directive in the dictionary, and then does the same as loop.
  1233.  
  1234. Command : leave 
  1235. Type    : compiler / flow control
  1236. Arguments       :  
  1237. Returns :  
  1238. Description
  1239. encloses the address of the control directive in the dictionary.
  1240.  
  1241. Command : begin 
  1242. Type    : compiler / flow control
  1243. Arguments       :  
  1244. Returns :  <entry>
  1245. Description
  1246. pushes the address of the next dictionary location to the stack.
  1247.  
  1248. Command : [ 
  1249. Type    : compiler / string output
  1250. Arguments       : 
  1251. Returns :  
  1252. Description
  1253. encloses the address of the control directive in the dictionary and then tokenises the characters up to the next ] into the dictionary space.
  1254. When the [ is executed the string between the left and right brackets  []  will be echo directly to the screen.
  1255.  
  1256. Command : { 
  1257. Type    : compiler / string output
  1258. Arguments       :  
  1259. Returns :  <string>
  1260. Description
  1261. encloses the address of the control directive in the dictionary and tokenises the buffer up to the next } into the dictionary space.
  1262. When then { is executed it will push the string between the left and right brackets {} onto the stack ( similar to the () in execute mode ).
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.